|
|
KCUnlock |
||||
| Header: | Keychain.h | Carbon status: | Under Evaluation | |
Displays a dialog box that prompts the user for a password in order before unlocking keychain.
OSStatus KCUnlock (
KCRef keychain,
StringPtr password
);
A reference to the keychain to unlock. Pass NULL to specify the default keychain. If you pass NULL and the default keychain is currently locked, the keychain will appear as the default choice. If you pass a locked keychain, KCUnlock will display the Unlock Keychain dialog box and the keychain will appear as the chosen menu item in keychain popup menu. If the default keychain is currently unlocked, the Unlock Keychain dialog box is not displayed and KCUnlock returns noErr.
A pointer to a Pascal string representing the password string for this keychain. Pass NULL if the user password is unknown. In this case, KCUnlock displays the Unlock Keychain dialog box, and the authentication user interface associated with the keychain about to be unlocked. If you specify an invalid password, you will not be able to unlock the keychain with a specified password until the machine is rebooted. In this case, KCUnlock returns errKCInteractionRequired.
A result code. The result code noErr does not guarantee that the specified keychain is unlocked, because the user can select any available keychain and unlock it. The result code errUserCanceled indicates that the user pressed the Cancel button in the Unlock Keychain dialog box. The result code errKCAuthFailed indicates that authentication failed because of too many unsuccessful retries. The result code errKCInteractionRequired indicates that user interaction is required to unlock the keychain. In this case, you will not be able to unlock the keychain with that password until the machine is rebooted.
In most cases, your application does not need to call the KCUnlock function directly, since most Keychain Manager functions that require an unlocked keychain call KCUnlock automatically. If your application needs to verify that a keychain is unlocked, call the function KCGetStatus.
You can also call the function kcunlock to display a user interface prompting the user to unlock a keychain. kcunlock requires that you pass a pointer to a C string instead of a pointer to a Pascal string in the password parameter.
The memory that the keychain reference occupies must be released by calling the function KCReleaseKeychain when you are finished with it.
KCUnlock replaces the function KCUnlockKeychain, which was available in Keychain Manager 1.0.
© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)